Translator Add-ons

Declared in:  be/translation/TranslatorAddOn.h
Library: libtranslation.so
more...

This section describes the functions and data that a translator add-on must (or can) supply. The translator add-ons that you create and install are loaded into a BTranslatorRoster object through its Default() or AddTranslators() function.

You compile your add-on as a shared library, link against libtranslation.so, and install the add-on object file in the Translators subdirectory of B_USER_ADDONS_DIRECTORY.

The table below briefly lists the translator add-on symbols:

Symbol	Required?	Description
translatorInfo	yes	long description of translator
translatorName	yes	short name of translator
translatorVersion	yes	translator version number
Identify()	yes	identify data in a BPositionIO
Translate()	yes	translate data from one format to another
inputFormats	no	list of supported input formats
outputFormats	no	list of supported output formats
GetConfigMessage()	no	save current configuration in a BMessage
MakeConfig()	no	create a view for user-configuration of translator

Translator Add-on Functions

GetConfigMessage()

status_t GetConfigMessage(BMessage *ioExtension)

Optional

This function stores the current configuration in the ioExtension in such a manner that it may be flattened, unflattened, and then passed to Translate() as an ioExtension.

Identify()

status_t Identify(BPositionIO *inSource,       const translation_format *inFormat,       BMessage *ioExtension,       translator_info *outInfo,       uint32 outType)

Required

If the translator understands how to convert the data contained in inSource to media type outType, it fills outInfo with details about the input format and return B_OK. If it doesn't know how to translate the data, it returns B_NO_TRANSLATOR.

The quality and capability fields in outInfo are used by the Translation Kit in selecting the best suited translator for a given translation, so it is best to be conservative in choosing these values.

If the media format doesn't have a type code in <be/support/TypeConstants.h> (as will most likely be the case), choose a reasonable value. For example, the Targa handler included with the BeOS distribution uses the type code 'TGA '.

The translator need not fill in the translator field in outInfo; BTranslatorRoster fills in this value for you.

Remember that inSource may be arriving from any source, including a live network feed. It's therefore best to steer clear of calls such as BPositionIO::Size() which force all the data out of the stream. Similarly, it is good practice to read only as much of the stream as you need.

inFormat, if it is not NULL, is provided as a hint to the format of the data in inSource. Since it is only a hint, the data may very well be in some other format.

ioExtension, if it is not NULL, contains additional information for the add-on. It is described at length in the section in BTranslatorRoster titled "Configuration".

outType may be zero, in which case any output format is acceptable.

MakeConfig()

status_t MakeConfig(BMessage *ioExtension,       BView **outView,       BRect *outExtent)

Optional

This function creates a new BView through which the user configures the add-on. For example, it could be used to control the degree of image compression used or the video frame rate. The bounds of the view are returned in outExtent, although it can be resized at will by an external source. Changes to the configuration take effect immediately, although translations should be carried out with the same parameters throughout.

Translate()

status_t Translate(BPositionIO *inSource,       const translator_info *inInfo,       BMessage *ioExtension,       uint32 outType,       BPositionIO *outDestination)

Required

The translator translates data from inSource to format outType, writing the output to outDestination. outType may be zero, in which case it is assumed to be the default format type for the media group. As in Identify(), inInfo serves as a hint to the format of the data in inSource. ioExtension fills its usual role as a container of configuration information. The function returns B_OK if it's able to convert the data successfully. If it's unable to do so, it returns either B_NO_TRANSLATOR or an error value as appropriate.

Translator Add-on Data

inputFormats , outputFormats

translation_format inputFormats[]; translation_format outputFormats[];

Optional

These arrays tell BTranslatorRoster which formats the add-on supports. If they are not exported by the translator, the add-on's Identify() will be called each time an application requests a translation. Each array ends in an empty translation_format structure, so a typical inputFormats would look like:

translation_format inputFormats[] = { { 'TGA ', B_TRANSLATOR_BITMAP, 0.6, 0.5, "image/targa", "Targa bitmap format" }, { B_TRANSLATOR_BITMAP, B_TRANSLATOR_BITMAP, 0.4, 0.6, "image/x-be-bitmap", "Be Bitmap format" }, { 0, 0, 0, 0, 0, 0 } };

and similarly for outputFormats.

translatorInfo , translatorName , translatorVersion

char translatorInfo[]; char translatorName[]; int32 translatorVersion;

Required

translatorInfo returns a pointer to the translator's long name, e.g. "aiff translator by the Pie Man (pie@the.man)".

translatorName returns a pointer to the translator's short name, e.g. "aiff translator". The short name should be appropriate for display in a menu.

translatorVersion gives an "MM.mm" version number for the translator. For example, a TranslatorVersion() of 314 is interpreted as version 3.14.